home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / Sambar Server.exe / _SETUP.1 / javaeng.jar / javax / servlet / http / HttpServletRequest.java < prev    next >
Encoding:
Java Source  |  2000-04-03  |  9.6 KB  |  348 lines
  1. /*
  2.  * HttpServletRequest.java -- Holds request data
  3.  *
  4.  * Copyright (c) 1998, 1999 by Free Software Foundation, Inc.
  5.  * Written by Paul Siegmann (pauls@euronet.nl)
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU Library General Public License as published
  9.  * by the Free Software Foundation, version 2. (see COPYING.LIB)
  10.  *
  11.  * This program is distributed in the hope that it will be useful, but
  12.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307 USA
  19.  */
  20.  
  21. package javax.servlet.http;
  22.  
  23. import java.util.Enumeration;
  24.  
  25. import javax.servlet.ServletRequest;
  26.  
  27. /**
  28.  * Contains all the client's request information.
  29.  * <B>Implementation note:</B> all the headername matching in this class should be case<B>in</B>sensitive.
  30.  *
  31. #ifdef SERVLET_2_0
  32.  * @version Servlet API 2.0 
  33. #endif
  34. #ifdef SERVLET_2_1
  35.  * @version Servlet API 2.1
  36. #endif
  37. #ifdef SERVLET_2_2
  38.  * @version Servlet API 2.2
  39. #endif
  40.  * @since Servlet API 1.0
  41.  */
  42. public interface HttpServletRequest
  43.     extends ServletRequest
  44. {
  45.     /**
  46.      * Gets the authorization scheme of this request.
  47.      * This is the same as the CGI request metadata <code>AUTH_TYPE</code>.
  48.      * See also section 11 of the HTTP/1.1 specification (RFC 2068).
  49.      *
  50.      * @since Servlet API 1.0
  51.      *
  52.      * @return Authorization scheme or null if not set    
  53.      */
  54.     String getAuthType();
  55.  
  56.  
  57.     /**
  58.      * Gets all the Cookies present in the request.
  59.      *
  60.      * @since Servlet API 2.0
  61.      *
  62.      * @return an array containing all the Cookies or an empty array if there
  63.      * are no cookies    
  64.      */
  65.     Cookie[] getCookies();
  66.  
  67.  
  68.     /** 
  69.      * Converts a given header parameter name to a date in the form of
  70.      * the number of milliseconds since 1 january 1970 midnight GMT.
  71.      * If the headername doesn't exist it returns -1;
  72.      * If the header can not be converted to a date it throws
  73.      * an IllegalArgumentException.
  74.      *
  75.      * @since Servlet API 1.0
  76.      *
  77.      * @param name the name of the header field (case insensitive)
  78.      * @return milliseconds since January 1, 1970, 00:00:00 GMT or -1 if the
  79.      * header does not exist.
  80.      * @exception IllegalArgumentException if the value is not a date
  81.      */
  82.     long getDateHeader(String name);
  83.  
  84.  
  85.     /**
  86.      * Gets a named header.
  87.      * returns null if the headername doesn't exist.
  88.      *
  89.      * @since Servlet API 1.0
  90.      *
  91.      * @param name the name of the header field (case insensitive)
  92.      * @return The value of the header or null if the header does not exist
  93.      */
  94.     String getHeader(String name);
  95.  
  96. #ifdef SERVLET_2_2
  97.  
  98.     /**
  99.      * XXX
  100.      *
  101.      * @since Servlet API 2.2
  102.      */
  103.     Enumeration getHeaders(String name);
  104.  
  105. #endif
  106.  
  107.     /**
  108.      * Gets an Enumeration with all the headernames.
  109.      * Note that the Servlet API 2.1 Specification says that if an
  110.      * implementation does not support this operation an empty enumeration
  111.      * should be returned, but the Servlet API documentation says that the
  112.      * implementation will return null.
  113.      *
  114.      * @since Servlet API 1.0
  115.      *
  116.      * @return Enumeration of all the header names or when this operation is
  117.      * not supported an empty Enumeration or null.
  118.      */
  119.     Enumeration getHeaderNames();
  120.  
  121.  
  122.     /**
  123.      * Gets a named header and returns it in the shape of an int.
  124.      * returns -1 if the headername doesn't exist.<BR>
  125.      * [MJW] What if the value is -1?
  126.      *
  127.      * @since Servlet API 1.0
  128.      *
  129.      * @param name the name of the header field (case insensitive)
  130.      * @return the value of the header field or -1 if the header does not exist
  131.      * @exception NumberFormatException if the headervalue can't be converted
  132.      * to an int.
  133.      */
  134.     int getIntHeader(String name) throws NumberFormatException;
  135.  
  136.  
  137.     /**
  138.      * Gets the method the client used.
  139.      * This is the same as the CGI request metadata <code>REQUEST_METHOD</code>.
  140.      * Possible return values are "GET", "HEAD", "POST", "PUT", "DELETE",
  141.      * "OPTIONS", "TRACE".
  142.      *
  143.      * @since Servlet API 1.0
  144.      *
  145.      * @return The method in question
  146.      */
  147.     String getMethod();
  148.  
  149. #ifdef SERVLET_2_2
  150.  
  151.     /**
  152.      * XXX
  153.      *
  154.      * @since Servlet API 2.2
  155.      */
  156.     String getContextPath();
  157.  
  158. #endif
  159.  
  160.     /**
  161.      * Extra path info. Everything after the actual Servlet except the query
  162.      * data. This is the same as the CGI request metadata <code>PATH_INFO</code>
  163.      * and identifies the source or sub-resource to be returned by the Servlet.
  164.      * <P>
  165.      * The function of this method could best be explained using an example.
  166.      * Client requests: www.foo_bar.com/servlets/myServlet/more/path?id=paul
  167.      * (where myServlet is a servlet)<BR>
  168.      * In this case this method would return "/more/path".
  169.      * <P>
  170.      * [MJW] Note that the Servlet 2.1 Spec says that the path info must be URL
  171.      * decoded although this was not required before 2.1 and I am not sure if
  172.      * that is the behaviour of the CGI request metadata <code>PATH_INFO</code>.
  173.      *
  174.      * @since Servlet API 1.0
  175.      *
  176.      * @return The path info or null when there is no path information.
  177.      */
  178.     String getPathInfo();
  179.  
  180.  
  181.     /**
  182.      * The filesystem path to the path info.
  183.      * Does the same as getPathInfo, but translates the result to a real path.
  184.      * This is the same as the CGI request metadata
  185.      * <code>PATH_TRANSLATED</code>.
  186.      * <P>
  187.      * [MJW] Can this be different from calling
  188.      * <code>ServletContext.getRealPath()</code> on the urldecoded result of
  189.      * <code>getPathInfo()</code>?
  190.      *
  191.      * @since Servlet API 1.0
  192.      *
  193.      * @return The filesystem path to the file indicated by the path info
  194.      *      or null if there is no path info
  195.      */
  196.     String getPathTranslated();
  197.  
  198.  
  199.     /**
  200.      * Gets the request's query string.
  201.      * The query string is the part of the request that follows the '?'.<BR>
  202.      * This is the same as the CGI request metadata <code>QUERY_STRING</code>.
  203.      *
  204.      * @since Servlet API 1.0
  205.      *
  206.      * @return the query string or null if there is no such part
  207.      */
  208.     String getQueryString();
  209.  
  210.  
  211.     /**
  212.      * Gets the username of the person sending the request.
  213.      * This is the same as the CGI request metadata <code>REMOTE_USER</code>.
  214.      *
  215.      * @since Servlet API 1.0
  216.      *
  217.      * @return User name
  218.      *      or null if the username wasn't in the HTTP authentication.
  219.      */
  220.     String getRemoteUser();
  221.  
  222.  
  223. #ifdef SERVLET_2_2
  224.  
  225.     /**
  226.      * XXX
  227.      *
  228.      * @since Servlet API 2.2
  229.      */
  230.     boolean isRemoteUserInRole(String role);
  231.  
  232.     /**
  233.      * XXX
  234.      *
  235.      * @since Servlet API 2.2
  236.      */
  237.     //Principal getRemoteUserPrincipal();
  238.  
  239. #endif
  240.  
  241.     /**
  242.      * Gets the session Id of this request that the client wanted.
  243.      * This id can differ from the id in the current session if the client
  244.      * recently had gotten a new session id for whatver reason.
  245.      *
  246.      * @since Servlet API 2.0
  247.      *
  248.      * @return The requested session id
  249.      */
  250.     String getRequestedSessionId();
  251.  
  252.  
  253.     /**
  254.      * Gets the requested URI.
  255.      * This includes both the path to the servlet and everything after
  256.      * that except the '?' and the query_string.
  257.      * <P>
  258.      * Note that the Servlet 2.1 Spec says that the URI must be decoded before
  259.      * being returned, but this was not required before the Servlet 2.1 API and
  260.      * normally all URIs are encoded.
  261.      *
  262.      * @since Servlet API 1.0
  263.      *
  264.      * @return The requested URI
  265.      */
  266.     String getRequestURI();
  267.  
  268.     /**
  269.      * Gets the part of the URI up to and including the servlet name.
  270.      * No path info or query string segments are included.
  271.      * This is the same as the CGI request metadata <code>SCRIPT_NAME</code>.
  272.      *
  273.      * @since Servlet API 1.0
  274.      */
  275.     String getServletPath();
  276.  
  277. #ifdef SERVLET_2_0
  278. #else
  279.  
  280.     /**
  281.      * Gets the HttpSession connected with the client sending the request.
  282.      * If the client didn't have a session connected with him
  283.      * then a new HttpSession will be created. To maintain a session this
  284.      * method must be called before the connection is flushed or closed.
  285.      * Same as calling <code>getSession(true)</code>.
  286.      *
  287.      * @since Servlet API 2.1
  288.      *
  289.      * @return The HttpSession connected with the client sending the request.
  290.      */
  291.     HttpSession getSession();
  292.  
  293. #endif
  294.  
  295.     /**
  296.      * Gets the HttpSession connected with the client sending the request.
  297.      * If the client didn't have a session connected with him,
  298.      * and <CODE>create</CODE> is true then a new HttpSession will be
  299.      * created. If <CODE>create</CODE> is false then <CODE>null</CODE>
  300.      * is returned. To maintain a session this
  301.      * method must be called before the connection is flushed or closed.
  302.      *
  303.      * @since Servlet API 2.0
  304.      *
  305.      * @return The HttpSession connected with the client sending the request.
  306.      */
  307.     HttpSession getSession(boolean create);
  308.  
  309.  
  310.     /**
  311.      * Checks whether the session connected with the id in the request is a
  312.      * valid one. Note that the requested session could differ from the actual
  313.      * session returned from <code>getSession</code>.
  314.      *
  315.      * @since Servlet API 2.0
  316.      */
  317.     boolean isRequestedSessionIdValid();
  318.  
  319.  
  320.     /**
  321.      * Returns whether the session id in the request was provided through a Cookie.
  322.      *
  323.      * @since Servlet API 2.0
  324.      */
  325.     boolean isRequestedSessionIdFromCookie();
  326.  
  327.  
  328. #ifdef SERVLET_2_0
  329. #else
  330.     /**
  331.      * Returns whether the session id in the request was encoded in the request URI.
  332.      * @since Servlet API 2.1
  333.      */
  334.     boolean isRequestedSessionIdFromURL();
  335. #endif
  336.  
  337.  
  338.     /**
  339.      * Returns whether the session id in the request was encoded in the request URI.
  340. #ifdef SERVLET_2_0
  341. #else
  342.      * @deprecated Use <code>isRequestedSessionIdFromURL</code>
  343. #endif
  344.      * @since Servlet API 2.0
  345.      */
  346.     boolean isRequestedSessionIdFromUrl();
  347. }
  348.